home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / man / cat.3 / CrtErrHdlr.3 < prev    next >
Text File  |  1995-07-25  |  14KB  |  265 lines
  1.  
  2.  
  3.  
  4.      TTTTkkkk____CCCCrrrreeeeaaaatttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr((((3333))))     TTTTkkkk (((( ))))      TTTTkkkk____CCCCrrrreeeeaaaatttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr((((3333))))
  5.  
  6.  
  7.  
  8.      _________________________________________________________________
  9.  
  10.      NNNNAAAAMMMMEEEE
  11.           Tk_CreateErrorHandler,  Tk_DeleteErrorHandler  -  handle   X
  12.           protocol errors
  13.  
  14.      SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  15.           ####iiiinnnncccclllluuuuddddeeee <<<<ttttkkkk....hhhh>>>>
  16.  
  17.           Tk_ErrorHandler
  18.           TTTTkkkk____CCCCrrrreeeeaaaatttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr(_d_i_s_p_l_a_y, _e_r_r_o_r, _r_e_q_u_e_s_t, _m_i_n_o_r, _p_r_o_c, _c_l_i_e_n_t_D_a_t_a)
  19.  
  20.           TTTTkkkk____DDDDeeeelllleeeetttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr(_h_a_n_d_l_e_r)
  21.  
  22.      AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  23.           Display           *_d_i_s_p_l_a_y     (in)      Display       whose
  24.                                                    errors  are  to  be
  25.                                                    handled.
  26.  
  27.           int               _e_r_r_o_r        (in)      Match  only   error
  28.                                                    events   with  this
  29.                                                    value    in     the
  30.                                                    _e_r_r_o_r__c_o_d_e   field.
  31.                                                    If -1,  then  match
  32.                                                    any      _e_r_r_o_r__c_o_d_e
  33.                                                    value.
  34.  
  35.           int               _r_e_q_u_e_s_t      (in)      Match  only   error
  36.                                                    events   with  this
  37.                                                    value    in     the
  38.                                                    _r_e_q_u_e_s_t__c_o_d_e field.
  39.                                                    If -1,  then  match
  40.                                                    any    _r_e_q_u_e_s_t__c_o_d_e
  41.                                                    value.
  42.  
  43.           int               _m_i_n_o_r        (in)      Match  only   error
  44.                                                    events   with  this
  45.                                                    value    in     the
  46.                                                    _m_i_n_o_r__c_o_d_e   field.
  47.                                                    If -1,  then  match
  48.                                                    any      _m_i_n_o_r__c_o_d_e
  49.                                                    value.
  50.  
  51.           Tk_ErrorProc      *_p_r_o_c        (in)      Procedure to invoke
  52.                                                    whenever  an  error
  53.                                                    event  is  received
  54.                                                    for   _d_i_s_p_l_a_y   and
  55.                                                    matches      _e_r_r_o_r,
  56.                                                    _r_e_q_u_e_s_t, and _m_i_n_o_r.
  57.                                                    NULL  means  ignore
  58.                                                    any        matching
  59.                                                    errors.
  60.  
  61.  
  62.  
  63.      Page 1                                          (printed 7/23/95)
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      TTTTkkkk____CCCCrrrreeeeaaaatttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr((((3333))))     TTTTkkkk (((( ))))      TTTTkkkk____CCCCrrrreeeeaaaatttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr((((3333))))
  71.  
  72.  
  73.  
  74.           ClientData        _c_l_i_e_n_t_D_a_t_a   (in)      Arbitrary  one-word
  75.                                                    value  to  pass  to
  76.                                                    _p_r_o_c.
  77.  
  78.           Tk_ErrorHandler   _h_a_n_d_l_e_r      (in)      Token   for   error
  79.                                                    handler  to  delete
  80.                                                    (return value  from
  81.                                                    a  previous call to
  82.                                                    TTTTkkkk____CCCCrrrreeeeaaaatttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr).
  83.      _________________________________________________________________
  84.  
  85.  
  86.      DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  87.           TTTTkkkk____CCCCrrrreeeeaaaatttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr arranges for  a  particular  procedure
  88.           (_p_r_o_c)  to  be called whenever certain protocol errors occur
  89.           on a particular display (_d_i_s_p_l_a_y).   Protocol  errors  occur
  90.           when  the X protocol is used incorrectly, such as attempting
  91.           to  map  a  window  that  doesn't  exist.   See   the   Xlib
  92.           documentation  for  XXXXSSSSeeeettttEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr for more information on
  93.           the kinds of errors that can occur.  For _p_r_o_c to be  invoked
  94.           to handle a particular error, five things must occur:
  95.  
  96.           [1]  The error must pertain to _d_i_s_p_l_a_y.
  97.  
  98.           [2]  Either the _e_r_r_o_r argument to TTTTkkkk____CCCCrrrreeeeaaaatttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr must
  99.                have  been  -1,  or  the  _e_r_r_o_r argument must match the
  100.                _e_r_r_o_r__c_o_d_e field from the error event.
  101.  
  102.           [3]  Either the _r_e_q_u_e_s_t  argument  to  TTTTkkkk____CCCCrrrreeeeaaaatttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr
  103.                must  have  been -1, or the _r_e_q_u_e_s_t argument must match
  104.                the _r_e_q_u_e_s_t__c_o_d_e field from the error event.
  105.  
  106.           [4]  Either the _m_i_n_o_r argument to TTTTkkkk____CCCCrrrreeeeaaaatttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr must
  107.                have  been  -1,  or  the  _m_i_n_o_r argument must match the
  108.                _m_i_n_o_r__c_o_d_e field from the error event.
  109.  
  110.           [5]  The protocol request to which the error  pertains  must
  111.                have  been  made when the handler was active (see below
  112.                for more information).
  113.  
  114.           _P_r_o_c  should  have  arguments  and  result  that  match  the
  115.           following type:
  116.                typedef int Tk_ErrorProc(
  117.                     ClientData _c_l_i_e_n_t_D_a_t_a,
  118.                     XErrorEvent *_e_r_r_E_v_e_n_t_P_t_r);
  119.           The _c_l_i_e_n_t_D_a_t_a parameter to _p_r_o_c is a copy of the _c_l_i_e_n_t_D_a_t_a
  120.           argument  given  to TTTTccccllll____CCCCrrrreeeeaaaatttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr when the callback
  121.           was  created.   Typically,  _c_l_i_e_n_t_D_a_t_a  points  to  a   data
  122.           structure  containing  application-specific information that
  123.           is needed to deal with the error.  _E_r_r_E_v_e_n_t_P_t_r is a  pointer
  124.           to  the  X error event.  The procedure _p_r_o_c should return an
  125.           integer value.  If it returns 0 it means that  _p_r_o_c  handled
  126.  
  127.  
  128.  
  129.      Page 2                                          (printed 7/23/95)
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.      TTTTkkkk____CCCCrrrreeeeaaaatttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr((((3333))))     TTTTkkkk (((( ))))      TTTTkkkk____CCCCrrrreeeeaaaatttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr((((3333))))
  137.  
  138.  
  139.  
  140.           the  error completely and there is no need to take any other
  141.           action for the error.  If it returns non-zero it means  _p_r_o_c
  142.           was unable to handle the error.
  143.  
  144.           If a value of NULL  is  specified  for  _p_r_o_c,  all  matching
  145.           errors  will  be ignored:  this will produce the same result
  146.           as if a procedure had been specified that always returns 0.
  147.  
  148.           If more than more than  one  handler  matches  a  particular
  149.           error,  then they are invoked in turn.  The handlers will be
  150.           invoked  in  reverse  order  of  creation:   most   recently
  151.           declared  handler  first.   If  any  handler returns 0, then
  152.           subsequent (older) handlers will  not  be  invoked.   If  no
  153.           handler  returns  0,  then  Tk  invokes  X'es  default error
  154.           handler, which  prints  an  error  message  and  aborts  the
  155.           program.   If  you wish to have a default handler that deals
  156.           with errors that  no  other  handler  can  deal  with,  then
  157.           declare it first.
  158.  
  159.           The X documentation states that ``the error  handler  should
  160.           not  call  any  functions  (directly  or  indirectly) on the
  161.           display that will generate protocol requests  or  that  will
  162.           look   for  input  events.''  This  restriction  applies  to
  163.           handlers declared by TTTTkkkk____CCCCrrrreeeeaaaatttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr;  disobey  it  at
  164.           your own risk.
  165.  
  166.           TTTTkkkk____DDDDeeeelllleeeetttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr may be called to delete a  previously-
  167.           created  error handler.  The _h_a_n_d_l_e_r argument identifies the
  168.           error handler, and should be a value returned by a  previous
  169.           call to TTTTkkkk____CCCCrrrreeeeaaaatttteeeeEEEEvvvveeeennnnttttHHHHaaaannnnddddlllleeeerrrr.
  170.  
  171.           A particular error handler applies to errors resulting  from
  172.           protocol    requests   generated   between   the   call   to
  173.           TTTTkkkk____CCCCrrrreeeeaaaatttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr and the call to TTTTkkkk____DDDDeeeelllleeeetttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr.
  174.           However,  the  actual  callback  to _p_r_o_c may not occur until
  175.           after the TTTTkkkk____DDDDeeeelllleeeetttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr call, due  to  buffering  in
  176.           the  client  and  server.   If  an error event pertains to a
  177.           protocol    request     made     just     before     calling
  178.           TTTTkkkk____DDDDeeeelllleeeetttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr,  then  the  error  event may not have
  179.           been processed before the TTTTkkkk____DDDDeeeelllleeeetttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr call.   When
  180.           this  situation  arises,  Tk will save information about the
  181.           handler and invoke the handler's _p_r_o_c later when  the  error
  182.           event  finally  arrives.  If an application wishes to delete
  183.           an error handler and know  for  certain  that  all  relevant
  184.           errors   have   been   processed,   it   should  first  call
  185.           TTTTkkkk____DDDDeeeelllleeeetttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr and then call XXXXSSSSyyyynnnncccc;  this will  flush
  186.           out  any  buffered requests and errors, but will result in a
  187.           performance penalty because it requires communication to and
  188.           from  the  X  server.  After the XXXXSSSSyyyynnnncccc call Tk is guaranteed
  189.           not to call any error  handlers  deleted  before  the  XXXXSSSSyyyynnnncccc
  190.           call.
  191.  
  192.  
  193.  
  194.  
  195.      Page 3                                          (printed 7/23/95)
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.      TTTTkkkk____CCCCrrrreeeeaaaatttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr((((3333))))     TTTTkkkk (((( ))))      TTTTkkkk____CCCCrrrreeeeaaaatttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr((((3333))))
  203.  
  204.  
  205.  
  206.           For the Tk error handling mechanism to work properly, it  is
  207.           essential that application code never calls XXXXSSSSeeeettttEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr
  208.           directly;      applications      should       use       only
  209.           TTTTkkkk____CCCCrrrreeeeaaaatttteeeeEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr.
  210.  
  211.  
  212.      KKKKEEEEYYYYWWWWOOOORRRRDDDDSSSS
  213.           callback, error, event, handler
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.      Page 4                                          (printed 7/23/95)
  262.  
  263.  
  264.  
  265.